<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
<!-- creator-locator.qdoc -->
  <title>Searching with the Locator | Qt Creator Manual</title>
  <link rel="stylesheet" type="text/css" href="style/offline-simple.css" />
  <script type="text/javascript">
    document.getElementsByTagName("link").item(0).setAttribute("href", "style/offline.css");
    // loading style sheet breaks anchors that were jumped to before
    // so force jumping to anchor again
    setTimeout(function() {
        var anchor = location.hash;
        // need to jump to different anchor first (e.g. none)
        location.hash = "#";
        setTimeout(function() {
            location.hash = anchor;
        }, 0);
    }, 0);
  </script>
</head>
<body>
<div class="header" id="qtdocheader">
  <div class="main">
    <div class="main-rounded">
      <div class="navigationbar">
        <table><tr>
<td ><a href="index.html">Qt Creator Manual</a></td><td >Searching with the Locator</td></tr></table><table class="buildversion"><tr>
<td id="buildversion" width="100%" align="right"><a href="index.html">Qt Creator Manual 4.11.1</a></td>
        </tr></table>
      </div>
    </div>
<div class="content">
<div class="line">
<div class="content mainContent">
  <link rel="prev" href="creator-editor-finding.html" />
  <link rel="next" href="creator-editor-refactoring.html" />
<p class="naviNextPrevious headerNavi">
<a class="prevPage" href="creator-editor-finding.html">Finding and Replacing</a>
<span class="naviSeparator">  &#9702;  </span>
<a class="nextPage" href="creator-editor-refactoring.html">Refactoring</a>
</p><p/>
<div class="sidebar">
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#using-locator-filters">Using Locator Filters</a></li>
<li class="level1"><a href="#configuring-locator-filters">Configuring Locator Filters</a></li>
<li class="level2"><a href="#adding-web-search-engines">Adding Web Search Engines</a></li>
<li class="level1"><a href="#creating-locator-filters">Creating Locator Filters</a></li>
<li class="level1"><a href="#configuring-locator-cache">Configuring Locator Cache</a></li>
<li class="level1"><a href="#executing-javascript">Executing JavaScript</a></li>
</ul>
</div>
<div class="sidebar-content" id="sidebar-content"></div></div>
<h1 class="title">Searching with the Locator</h1>
<span class="subtitle"></span>
<!-- $$$creator-editor-locator.html-description -->
<div class="descr"> <a name="details"></a>
<p>You can find the locator in the bottom left of the Qt Creator window.</p>
<p class="centerAlign"><img src="images/qtcreator-locator.png" alt="" /></p><p>To activate the locator:</p>
<ul>
<li>Press <b>Ctrl+K</b> (<b>Cmd+K</b> on <a href="nolink">macOS</a>).</li>
<li>Select <b>Tools</b> &gt; <b>Locate</b>.</li>
<li>Select <b>Edit</b> &gt; <b>Go to Line</b>.</li>
<li>Click the line and column indicator on the <a href="creator-coding-navigating.html#using-the-editor-toolbar">editor toolbar</a>.</li>
</ul>
<p>To open a QML file called <i>HelloWorld.qml</i> in the currently open project using the locator:</p>
<ol class="1" type="1"><li>Activate the locator by pressing <b>Ctrl+K</b>.</li>
<li>Start typing the filename.<p class="centerAlign"><img src="images/qtcreator-locator-open.png" alt="" /></p></li>
<li>Move to the filename in the list and press <b>Enter</b>.<p>The file opens in the editor.</p>
</li>
<li>To move to a line in the file, enter the line number in the locator.</li>
</ol>
<p>To move directly to a particular line and column in the document when you open the document, append them to the file name in the locator, separated by plus signs (+) or colons (:). For example, to open <i>HelloWorld.qml</i> to line 41 and column 2, enter: <code>HelloWorld.qml:41:2</code>.</p>
<p>If the path to a file is very long, it might not fit into the locator window. To view the full path, press <b>Alt</b> when the filename is selected or use the handle next to the locator window to increase the window width.</p>
<p>It is also possible to enter only a part of a search string. As you type, the locator shows the occurrences of that string regardless of where in the name of an component it appears. Some locator filters, such as colon and <code>m</code>, support <i>fuzzy</i> matching, which means that you can enter the uppercase letters to locate a symbol when using camel case or the letters after the underscore when using snake case.</p>
<p>To narrow down the search results, you can use the following wildcard characters:</p>
<ul>
<li>To match any number of any or no characters, enter <code>*</code>.</li>
<li>To match a single instance of any character, enter <code>?</code>.</li>
</ul>
<a name="using-locator-filters"></a>
<h2 id="using-locator-filters">Using Locator Filters</h2>
<p>The locator enables you to browse not only files, but any items defined by <b>locator filters</b>. The filters that are available depend on the file type:</p>
<ul>
<li>Locating any open document (<code>o</code>)</li>
<li>Locating files anywhere on your file system (<code>f</code>)</li>
<li>Locating files belonging to your project (<code>p</code>), such as source, header, resource, and <code>.ui</code> files, or to any project (<code>a</code>)</li>
<li>Locating bookmarks (<code>b</code>). For more information, see <a href="creator-coding-navigating.html#using-bookmarks">Using Bookmarks</a>.</li>
<li>Locating class (<code>c</code>), enum, and function (<code>m</code>) definitions in your project or anywhere referenced from your project (<code>:</code>)</li>
<li>Locating QML methods (<code>m</code>)</li>
<li>Locating symbols in the current document (<code>.</code>)</li>
<li>Locating a specific line and column in the document displayed in your editor (<code>l &lt;line_number&gt;:&lt;column_number&gt;</code>)</li>
<li>Opening help topics, including Qt documentation (<code>?</code>)</li>
<li>Performing web searches (<code>r</code>)</li>
<li>Running text editing macros that you record and save (<code>rm</code>). For more information, see <a href="creator-macros.html">Using Text Editing Macros</a></li>
<li>Executing JavaScript (<code>=</code>), especially useful for calculations. For more information, see <a href="creator-editor-locator.html#executing-javascript">Executing JavaScript</a>.</li>
<li>Executing shell commands (<code>!</code>)</li>
<li>Executing version control system commands (<code>git</code>). For more information, see <a href="creator-version-control.html">Using Version Control Systems</a></li>
<li>Triggering menu items from the main menu (<code>t</code>)</li>
<li>Running external tools (<code>x</code>)</li>
<li>Using CMake to build the project for the current run configuration (<code>cm</code>). For more information, see <a href="creator-project-cmake.html">Setting up CMake</a>.</li>
<li>Opening the CMakeLists.txt file for the current run configuration in the editor (<code>cmo</code>). This is the same build target as when you select <b>Build</b> &gt; <b>Build for Run Configuration</b>.</li>
</ul>
<p>To use a specific locator filter, type the assigned prefix followed by <b>Space</b>. The prefix is usually a single character. Then type the search string (typically, a filename or class name) or the command to execute.</p>
<p>You can also double-click a locator filter in the filter list to use it. You can use the up and down arrow keys or the <b>Ctrl+P</b> and <b>Ctrl+N</b> keyboard shortcuts to move up and down the list, and then press <b>Enter</b> to use the selected filter.</p>
<p>For example, to locate symbols matching <a href="http://doc.qt.io/qt-5/qdatastream.html">QDataStream</a>:</p>
<ol class="1" type="1"><li>Activate the locator.</li>
<li>Enter a colon (:) followed by a space and the upper case letters in the symbol name (<a href="http://doc.qt.io/qt-5/qdatastream.html">QDataStream</a>):<pre class="cpp">

  : qds

</pre>
<p>The locator lists the results.</p>
<p class="centerAlign"><img src="images/qtcreator-navigate-popup.png" alt="" /></p></li>
</ol>
<p>Filters locating files also accept paths, such as <code>tools/*main.cpp</code>. Filters locating class and function definitions also accept namespaces, such as <code>Utils::*View</code>. For example, to create a new file and open it in the editor, type <code>f</code> followed by <b>Space</b>, followed by path and file name, and then press <b>Enter</b>.</p>
<p>You can use the filter that triggers menu commands to open sessions. Enter <code>t yoursess</code> or <code>t sess yoursess</code> to trigger <b>File</b> &gt; <b>Sessions</b> &gt; <i>yoursessionname</i>.</p>
<p>By default, the following filters are enabled and you do not need to use their prefixes explicitly:</p>
<ul>
<li>Going to a line and column in the current file (<code>l</code>).</li>
<li>Going to an open file (<code>o</code>).</li>
<li>Going to a file in any open project (<code>a</code>).</li>
</ul>
<p>If locator does not find some files, you can add them to the <code>DISTFILES</code> variable in the <code>.pro</code> file to include them into the distribution tarball of your project and thus make them known to Qt Creator as well.</p>
<a name="configuring-locator-filters"></a>
<h2 id="configuring-locator-filters">Configuring Locator Filters</h2>
<p>If the default filters do not match your use case, you can check whether you can change them. For all filters, you can change the filter prefix and restrict the search to items that match the filter.</p>
<p>To configure a locator filter:</p>
<ol class="1" type="1"><li>In the locator, click <img src="images/magnifier.png" alt="" /> (<b>Options</b>) and select <b>Configure</b> to open the <b>Locator</b> options.</li>
<li>Select a filter, and then select <b>Edit</b>.</li>
<li>Specify the prefix string.</li>
<li>To implicitly include the filter even when not typing a prefix as a part of the search string, select <b>Include by default</b>.</li>
<li>Specify other available options. For more information, see <a href="creator-editor-locator.html#adding-web-search-engines">Adding Web Search Engines</a>.</li>
</ol>
<a name="adding-web-search-engines"></a>
<h3 id="adding-web-search-engines">Adding Web Search Engines</h3>
<p>You can use the <b>Web Search (r)</b> locator filter to perform web searches. URLs and search commands for Bing, Google, Yahoo! Search, cplusplus.com, and Wikipedia are configured by default.</p>
<p>To find out the format of the search command to use for your favorite web search engine, perform a search in your browser and copy the resulting URL to the locator filter configuration. Replace the search term with the variable <code>%1</code>.</p>
<p>To add URLs and search commands to the list:</p>
<ol class="1" type="1"><li>Select <b>Tools</b> &gt; <b>Options</b> &gt; <b>Environment</b> &gt; <b>Locator</b> &gt; <b>Web Search (prefix: r)</b> &gt; <b>Edit</b>.</li>
<li>Select <b>Add</b> to add a new entry to the list.<p class="centerAlign"><img src="images/qtcreator-add-online-doc.png" alt="&quot;Filter Configuration dialog&quot;" /></p></li>
<li>Double-click the new entry to specify a URL and a search command. For example, <code>http://www.google.com/search?q=%1</code>.</li>
<li>Click <b>OK</b>.</li>
</ol>
<a name="creating-locator-filters"></a>
<h2 id="creating-locator-filters">Creating Locator Filters</h2>
<p>To quickly access files not directly mentioned in your project, you can create your own locator filters. That way you can locate files in a directory structure you have defined.</p>
<p>To create a locator filter:</p>
<ol class="1" type="1"><li>In the locator, select <b>Options</b> &gt; <b>Configure</b> to open the <b>Locator</b> options.<p class="centerAlign"><img src="images/qtcreator-locator-customize.png" alt="" /></p></li>
<li>Click <b>Add</b>.</li>
<li>In the <b>Filter Configuration</b> dialog:<p class="centerAlign"><img src="images/qtcreator-navigate-customfilter.png" alt="" /></p><ul>
<li>In the <b>Name</b> field, enter a name for your filter.</li>
<li>In the <b>Directories</b> field, select at least one directory. The locator searches directories recursively.</li>
<li>In the <b>File pattern</b> field, specify file patterns to restrict the search to files that match the pattern. Use a comma separated list. For example, to search for all <code>.qml</code> and <code>.ui.qml</code> files, enter <code>*.qml,*.ui.qml</code></li>
<li>In the <b>Exclusion pattern</b> field, specify file patterns to omit files from the search.</li>
<li>In the <b>Prefix</b> field, specify the prefix string.<p>To implicitly include the filter even when not typing a prefix as a part of the search string, select <b>Include by default</b>.</p>
</li>
</ul>
</li>
<li>Click <b>OK</b>.</li>
</ol>
<a name="configuring-locator-cache"></a>
<h2 id="configuring-locator-cache">Configuring Locator Cache</h2>
<p>The locator searches the files matching your file pattern in the directories you have selected and caches that information. The cache for all default filters is updated as you write your code. By default, Qt Creator updates the filters created by you once an hour.</p>
<p>To update the cached information manually, select <b>Options</b> &gt; <b>Refresh</b> in the locator.</p>
<p>To set a new cache update time:</p>
<ol class="1" type="1"><li>Select <b>Tools</b> &gt; <b>Options</b> &gt; <b>Environment</b> &gt; <b>Locator</b>.</li>
<li>In <b>Refresh interval</b>, define new time in minutes.</li>
</ol>
<a name="executing-javascript"></a>
<h2 id="executing-javascript">Executing JavaScript</h2>
<p>The locator provides access to a JavaScript interpreter, that can be used to perform calculations.</p>
<p>Beside simple mathematical operations, like ((1 + 2) * 3), the following built-in functions exist:</p>
<div class="table"><table class="generic">
 <thead><tr class="qt-style"><th >Function</th><th >Purpose</th></tr></thead>
<tr valign="top" class="odd"><td >abs(x)</td><td >Returns the absolute value of x</td></tr>
<tr valign="top" class="even"><td >acos(x)</td><td >Returns the arccosine of x, in radians</td></tr>
<tr valign="top" class="odd"><td >asin(x)</td><td >Returns the arcsine of x, in radians</td></tr>
<tr valign="top" class="even"><td >atan(x)</td><td >Returns the arctangent of x, in radians</td></tr>
<tr valign="top" class="odd"><td >atan2(x, y)</td><td >Returns the arctangent of the quotient of its arguments</td></tr>
<tr valign="top" class="even"><td >bin(x)</td><td >Returns the binary representation of x</td></tr>
<tr valign="top" class="odd"><td >ceil(x)</td><td >Returns the value of x rounded up to the next integer</td></tr>
<tr valign="top" class="even"><td >cos(x)</td><td >Returns the cosine of x (x is in radians)</td></tr>
<tr valign="top" class="odd"><td >exp(x)</td><td >Returns the value of E to the power of x</td></tr>
<tr valign="top" class="even"><td >e()</td><td >Returns Euler's number E (2.71828..&#x2e;)</td></tr>
<tr valign="top" class="odd"><td >floor(x)</td><td >Returns the value of x rounded down to the next integer</td></tr>
<tr valign="top" class="even"><td >hex(x)</td><td >Returns the hexadecimal representation of x</td></tr>
<tr valign="top" class="odd"><td >log(x)</td><td >Returns the natural logarithm (base E) of x</td></tr>
<tr valign="top" class="even"><td >max([value1[, value2[, ..&#x2e;]]])</td><td >Returns the highest value of the given numbers</td></tr>
<tr valign="top" class="odd"><td >min([value1[, value2[, ..&#x2e;]]])</td><td >Returns the lowest value of the given numbers</td></tr>
<tr valign="top" class="even"><td >oct(x)</td><td >Returns the octal representation of x</td></tr>
<tr valign="top" class="odd"><td >pi()</td><td >Returns PI (3.14159..&#x2e;)</td></tr>
<tr valign="top" class="even"><td >pow(x, y)</td><td >Returns the value of x to the power of y</td></tr>
<tr valign="top" class="odd"><td >random()</td><td >Returns a random number between 0 and 1</td></tr>
<tr valign="top" class="even"><td >round(x)</td><td >Returns the value of x rounded to the next integer</td></tr>
<tr valign="top" class="odd"><td >sin(x)</td><td >Returns the sine of x (x is in radians)</td></tr>
<tr valign="top" class="even"><td >sqrt(x)</td><td >Returns the square root of x</td></tr>
<tr valign="top" class="odd"><td >tan(x)</td><td >Returns the tangent of x (x is in radians)</td></tr>
</table></div>
</div>
<!-- @@@creator-editor-locator.html -->
<p class="naviNextPrevious footerNavi">
<a class="prevPage" href="creator-editor-finding.html">Finding and Replacing</a>
<span class="naviSeparator">  &#9702;  </span>
<a class="nextPage" href="creator-editor-refactoring.html">Refactoring</a>
</p>
        </div>
       </div>
   </div>
   </div>
</div>
<div class="footer">
   <p>
   <acronym title="Copyright">&copy;</acronym> 2019 The Qt Company Ltd.
   Documentation contributions included herein are the copyrights of
   their respective owners.<br>    The documentation provided herein is licensed under the terms of the    <a href="http://www.gnu.org/licenses/fdl.html">GNU Free Documentation    License version 1.3</a> as published by the Free Software Foundation.<br>    Qt and respective logos are trademarks of The Qt Company Ltd.     in Finland and/or other countries worldwide. All other trademarks are property
   of their respective owners. </p>
</div>
</body>
</html>
